home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 22 / 9 / DISK2290.ZIP / NG_MAKER.DOC < prev    next >
Text File  |  1980-01-01  |  29KB  |  659 lines
  1. Page 1                  Automatic Code Documentation       
  2.                   Automatic Source Code Documentation                  Automatic Source Code Documentation
  3.                   Copyright Steven W. Kurtz, 1989-90                  Copyright Steven W. Kurtz, 1989-90
  4.                           All rights reserved                          All rights reserved
  5.  
  6.  
  7. Table of contents
  8.  
  9.  
  10.  
  11. Introduction                                               2
  12. Registration                                               2
  13. Problems NG_MAKER addresses                                2
  14. The NG_MAKER system design                                 3
  15. What if you don't use make?                                4
  16. Modifications to the make file                             4
  17. Macros and NG_MAKER                                        8
  18. Modifications to the project source code                   9
  19. Program module descriptions                               10
  20. Running NG_MAKER                                          11
  21. A Note for PC-Browse users                                11
  22. Compiling Norton Guides                                   11
  23. About the author                                          12
  24. Copyright notice and license                              12
  25. Warranty                                                  12
  26. Registration                                              13
  27. Technical support                                         13
  28. Version History                                           13
  29.  
  30.  
  31. Page 2                  Automatic Code Documentation       
  32.  
  33.  
  34. INTRODUCTION:_____________
  35.  
  36. This program is designed to be used in conjunction with the Norton
  37. Guides, published by Peter Norton Computing, and PC-Browse published
  38. by QuickSoft. NG_MAKER will read the ascii source code for any program
  39. and extract the comments which indicate the purpose, function, and
  40. expectations of the various building blocks of your program.
  41.  
  42. NG_MAKER will combine and assemble these comments into a database file
  43. compatible with the Norton Guides or PC-Browse. Once completed, you
  44. will be free to call up either program and review at a glance the
  45. various building blocks that make up the program you are working on.
  46.  
  47.  
  48. REGISTRATION:_____________
  49.  
  50. Registration (for the paultry sum of $25) will avail you of the latest
  51. version of NG_MAKER and every major upgrade thereafter.  If you so
  52. request, I will also send you the latest version of Quicksoft's
  53. excellent PC-Browse program.  I am one of the beta testers for this
  54. product.
  55.  
  56. I am always interested in suggestions for improvement.  You may mail
  57. them or send them EMAIL (Via Compuserve at 73577,2271 or via Prodigy
  58. at MDKS67A).
  59.  
  60.  
  61. PROBLEMS NG_MAKER ADDRESSES:____________________________
  62.  
  63. As a the coding of a program develops, it is common (and desirable) to
  64. break the program into smaller files that are written and then linked
  65. together in some fashion.   Each file will consist of one or more
  66. "building blocks" - commonly called Subroutines, Procedures,  or building blocks                                                
  67. Functions (depending on the language). For the purpose of this manual,
  68. we will simply refer to all of them as "PROCEDURES".                                        PROCEDURES  
  69.  
  70. Which file contains a particular procedure soon becomes more than an
  71. average person can remember. To make programming as easy as possible,
  72. the following information should also be available:
  73.  
  74. -      The line number that the procedure starts at.  Most editors have
  75.        a feature to jump to a particular line.  This is much faster then
  76.        having to use the search command to locate the starting point of
  77.        a procedure.
  78.  
  79. -      The parameters that a particular procedure expects, what
  80.        registers or variables it alters, and other major components it
  81.        uses.
  82.  
  83.  
  84. Page 3                  Automatic Code Documentation       
  85. -      More than one programmer may be working on the project.  It
  86.        becomes vital (but more difficult) for one programmer to know
  87.        the manner and expectations of a particular piece of code
  88.        written by a cohort.
  89.  
  90. -      NG_MAKER can be used by a project manager to keep control on
  91.        the revision history for project modules.
  92.  
  93.  
  94. THE NG_MAKER SYSTEM DESIGN__________________________
  95.  
  96. NG_MAKER is designed to work in intimate cooperation with MicroSoft
  97. compatible MAKE files that control the compilation of large projects.
  98. Using NG_MAKER will require that you make small changes in your Make
  99. file and to the source code for your project.  In each case, the
  100. changes are all "hidden" behind Remark symbols, so they are completely
  101. invisible to your compiler/assembler.
  102.  
  103.  
  104. Refer to the following block diagram in the explanation that follows.
  105.  
  106.  
  107.      ┌──────┐
  108.      │ MAKE │                                   ┌───────────────┐
  109.      │ FILE │                              ┌────│ Source file #1│
  110.      └──────┘                              │    └───────────────┘
  111.         │                                  │
  112.         │        ╔══════════════════╗ <────┘    ┌───────────────┐
  113.         └───────>║     NG_MAKER     ║ <─────────│ Source file #2│
  114.                  ╚══════════════════╝ <────┐    └───────────────┘
  115.                           ║                │
  116.                           ║                │    ┌───────────────┐
  117.                           ║                └────│ Source file #n│
  118.                ╔══════════╩══════════╗          └───────────────┘
  119.                V                     ║
  120.        ┌─────────────────┐           ║
  121.        │  Norton Guide   │           ║
  122.        │    Compiler     │           ║
  123.        └─────────────────┘           ║
  124.                ║                     ║
  125.                V                     ║
  126.        ┌─────────────────┐           ║
  127.        │  Norton Guide   │           ║
  128.        │     Linker      │           ║
  129.        └─────────────────┘           ║
  130.                ║                     ║
  131.                V                     V
  132.           NORTON GUIDE           PC-BROWSE
  133.             DATABASE               FILE
  134.  
  135.  
  136.  
  137. NG_MAKER reads the contents of the Make file.  It gains the following
  138. information from that file.
  139.  
  140. -      What symbol the files that follow use to indicate the start of
  141.        a remark line.
  142.  
  143. -      What symbol (if any) the files that follow use to indicate the
  144. Page 4                  Automatic Code Documentation       
  145.        end of a remark line.
  146.  
  147. Page 5                  Automatic Code Documentation       
  148. -      The subdirectory and filename for the output file that will be
  149.        used to create the actual database.
  150.  
  151. -      The name of the project.  This line is displayed when Options                                                             O      
  152.        Database is selected from the Norton Guide main menu.       D                                                    
  153.  
  154. -      The list of source code files that are to be analyzed.
  155.  
  156. -      Where, in the list of source code files, a new database element
  157.        is to be started (this applies only to Norton Guides).
  158.  
  159.  
  160.  
  161. NG_MAKER will then read each source code file that was mentioned in
  162. the Make file. From each file, it will get the following information:
  163.  
  164. -      A File Summary (optional).
  165.  
  166. -      The name for each procedure.
  167.  
  168. -      The line number that the procedure starts at.
  169.  
  170. -      Comments and remarks, written by you, about how the procedure
  171.        works.
  172.  
  173. -      Other pertinent cross references that would help explain how
  174.        the procedure works.  These will be combined to form a
  175.        "See Also:" line.
  176.  
  177. After all the files have been read, the output file that was specified
  178. in the Make file will be written on the disk.
  179.  
  180. When using the Norton Guides, a batch file will compile each element
  181. of the database and then link them together to create the final
  182. product. These two steps require the NGC.EXE and NGML.EXE programs
  183. that come with the Norton Guides.
  184.  
  185. WHAT IF YOU DON'T USE MAKE?___________________________
  186.  
  187. Don't worry! NG_MAKER does not require that your program development                               require                              
  188. system use MAKE.  The commands are compatible with MAKE should you do.
  189. If you do not, simply construct a file that contains nothing but the
  190. NG_MAKER keywords.
  191.  
  192.  
  193. MODIFICATIONS TO THE MAKE FILE______________________________
  194.  
  195. A MicroSoft-compatible Make file will use the # symbol as a remark
  196. character.  Any text placed behind this symbol will become invisible
  197. to the MAKE program. For this very reason, all NG_MAKER code words
  198. start with the two "#!" symbols.  The ! insures that an innocent
  199. comment is not mistakenly interpreted as an NG_MAKER keyword. Here is
  200. Page 6                  Automatic Code Documentation       
  201. a short and simple file to illustrate how an NG_MAKER compatible Make
  202. file would look. All lines that do not start with #! are lines that
  203. MAKE.EXE would interpret and execute.  If you are curious as to how
  204. they work, refer to the appropriate chapter in your manual.
  205.  
  206.  
  207.  
  208. #!NAME: Disk Peek project#!NAME: Disk Peek project
  209. #!OUT: C:\BROWSE\DSKPEEK#!OUT: C:\BROWSE\DSKPEEK
  210. #!REMARK: ;#!REMARK: ;
  211. #!ENDMARK:#!ENDMARK:
  212.  
  213. #!SOURCE: C:\ASSEMBLR\DP1.ASM#!SOURCE: C:\ASSEMBLR\DP1.ASM
  214. DP1.OBJ: C:\ASSEMBLR\DP1.ASM  C:\ASSEMBLR\MACROS.INC  C:\ASSEMBLR\DP.EQUDP1.OBJ: C:\ASSEMBLR\DP1.ASM  C:\ASSEMBLR\MACROS.INC  C:\ASSEMBLR\DP.EQU
  215.   MASM C:\ASSEMBLR\DP1.ASM;  MASM C:\ASSEMBLR\DP1.ASM;
  216.  
  217. #!SOURCE: C:\ASSEMBLR\DP2.ASM#!SOURCE: C:\ASSEMBLR\DP2.ASM
  218. DP2.OBJ: C:\ASSEMBLR\DP2.ASM  C:\ASSEMBLR\MACROS.INC  C:\ASSEMBLR\DP.EQUDP2.OBJ: C:\ASSEMBLR\DP2.ASM  C:\ASSEMBLR\MACROS.INC  C:\ASSEMBLR\DP.EQU
  219.   MASM C:\ASSEMBLR\DP2.ASM;  MASM C:\ASSEMBLR\DP2.ASM;
  220.  
  221. DP.EXE: DP1.OBJ DP2.OBJDP.EXE: DP1.OBJ DP2.OBJ
  222.   LINK  DP1.OBJ+DP2.OBJ,DP.EXE;  LINK  DP1.OBJ+DP2.OBJ,DP.EXE;
  223.  
  224.  
  225.  
  226.  
  227. Notice how the #!SOURCE lines are placed right next to the Make line
  228. that affects the same file.  This is not absolutely required, but will
  229. help you later should you ever change or add a filename.  The keywords
  230. that you see are explained in detail in the following pages.
  231.  
  232.  
  233. #!NAME:#!NAME:
  234.  
  235. This line will show up when Norton Guides' Options Database list shows                                           O       D                  
  236. the list of databases available.  PC-Browse users will find this title
  237. placed at the beginning of their database file.  EXAMPLES:
  238.  
  239. #!NAME: New spreadsheet project
  240.  
  241. #!NAME: My special word processor
  242.  
  243.  
  244. #!OUT:#!OUT:
  245.  
  246. This command will tell NG_MAKER the name for the output file.  The
  247. filename that ends the path should be no longer than 7 characters, and
  248. must not contain an extension.  To illustrate, the following lines
  249. would not be valid:
  250.  
  251. #!OUT: C:\NORGUIDE\MYSAMPLE           "MYSAMPLE" is too long.#!OUT: C:\NORGUIDE\MYSAMPLE            ________              
  252.  
  253. Page 7                  Automatic Code Documentation       
  254. #!OUT: C:\NORGUIDE\MYSMPLE.OUT        "MYSMPLE.OUT" has an extension.#!OUT: C:\NORGUIDE\MYSMPLE.OUT         ___________                   
  255.  
  256.  
  257. For Guide users, it is recommended that the OUT file be directed to
  258. the same directory that holds the Norton Guide program, NGC.EXE and
  259. NGML.EXE.
  260.  
  261. For Browse users, NG_MAKER will take this file name and append a
  262. ".BRS" extension to the end.
  263.  
  264.  
  265. #!SOURCE:#!SOURCE:
  266.  
  267. This is the most important keyword for NG_MAKER.  You will have one of
  268. these lines for each source code file NG_MAKER will read. Here are
  269. some examples
  270.  
  271. #!SOURCE: C:\PROJK\EDITOR.C#!SOURCE: C:\PROJK\EDITOR.C
  272. #!SOURCE: F:INCLUDER.ASM#!SOURCE: F:INCLUDER.ASM
  273. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.010#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.010
  274.  
  275.  
  276. #!REMARK:#!REMARK:
  277.  
  278. This keyword tells NG_MAKER what the remark character(s) are for the
  279. source code it will examine.  The default is a semicolon  (the author
  280. of NG_MAKER is an ardent assembly language programmer).
  281.  
  282. Pascal programmers would include the line:
  283.  
  284.                     #!REMARK:   {                    #!REMARK:   {
  285.        or
  286.                     #!REMARK:   (*                    #!REMARK:   (*
  287.  
  288.     and C programmer would use
  289.  
  290.  
  291.                     #!REMARK:   /*                    #!REMARK:   /*
  292.  
  293.  
  294. #!ENDMARK:#!ENDMARK:
  295. Some languages have a matching end-remark symbol. For these cases,
  296. include the command
  297.                        #!ENDMARK:                       #!ENDMARK:
  298.  
  299. followed by the appropriate symbol(s) for your language.
  300.  
  301. In many instances, a project will be written in more than one language
  302. (C and Assembler, for instance).  The REMARK and ENDMARK indicators
  303. can be altered any number of times to fit the changing situation.
  304.  
  305. A note of caution:  some languages will never use the ENDMARK keyword
  306. Page 8                  Automatic Code Documentation       
  307. (Assembler, Quick & TurboBasic).  However, you may be switching from a
  308. language that DOES.  To avoid complications, make sure you include the
  309. line :
  310.                        #!ENDMARK:                       #!ENDMARK:
  311.  
  312. with nothing after it.  The following lines illustrate this concept.
  313. The lines that MAKE.EXE would actually execute have been removed for
  314. clarity.
  315.  
  316. #!NAME: World's best TSR program#!NAME: World's best TSR program
  317. #!OUT: C:\BROWSE\PROJ-X#!OUT: C:\BROWSE\PROJ-X
  318. #!REMARK: /*                            <----these two lines set up#!REMARK: /*                                                       
  319. #!ENDMARK: */                           <----the remarks for the C#!ENDMARK: */                                                     
  320. #!SOURCE: C:\MYPROJ\MODULE1.C                files that follow.#!SOURCE: C:\MYPROJ\MODULE1.C                                  
  321. #!SOURCE: C:\MYPROJ\MODULE2.C#!SOURCE: C:\MYPROJ\MODULE2.C
  322. #!SOURCE: C:\MYPROJ\MODULE3.C#!SOURCE: C:\MYPROJ\MODULE3.C
  323. #!REMARK: ;                             <----Some assembler files need#!REMARK: ;                                                           
  324. #!ENDMARK:                                   to be read, so switch to#!ENDMARK:                                                           
  325. #!SOURCE: C:\MYPROJ\MODULE4.ASM              using a semicolon for the#!SOURCE: C:\MYPROJ\MODULE4.ASM                                       
  326. #!SOURCE: C:\MYPROJ\MODULE5.ASM              remark character (nothing#!SOURCE: C:\MYPROJ\MODULE5.ASM                                       
  327. #!SOURCE: C:\MYPROJ\MODULE6.ASM              for "ENDMARK").#!SOURCE: C:\MYPROJ\MODULE6.ASM                             
  328. #!REMARK: /*#!REMARK: /*
  329. #!ENDMARK: */                           <----back to C. change remark#!ENDMARK: */                                                        
  330. #!SOURCE: C:\MYPROJ\MODULE7.C                characters again.#!SOURCE: C:\MYPROJ\MODULE7.C                                 
  331.  
  332. #!BREAK:#!BREAK:
  333.  
  334. The situation may occur that you have more procedures than the
  335. Norton Guides can hold. It may report that "the list of short entries
  336. is too long" during the compilation process.  The final key word
  337. handles this situation. Place it as many times as necessary in the
  338. list of source files like this:
  339.  
  340. #!NAME: Project SS#!NAME: Project SS
  341. #!OUT: D:\NORGUIDE\SS#!OUT: D:\NORGUIDE\SS
  342. #!REMARK: ;#!REMARK: ;
  343. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.010#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.010
  344. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.020#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.020
  345. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.030#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.030
  346. #!BREAK:#!BREAK:
  347. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.040#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.040
  348. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.050#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.050
  349. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.060#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.060
  350. #!BREAK:#!BREAK:
  351.  
  352. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.110#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.110
  353. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.120#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.120
  354. #!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.130#!SOURCE: D:\ASSEMBLR\SS_SRCE\SS.130
  355.  
  356.  
  357.  
  358. This means that procedures in SS.010 through SS.030 will appear in
  359. Page 9                  Automatic Code Documentation       
  360. Procedure Group A, SS.040 through SS.060 will appear in Procedure
  361. Group B and so on. This will result in the top line of the Norton
  362. Guide looking somewhat like this:
  363.  
  364.    Expand     Search...    Options     By_Group     Sorted
  365.  ────────────────────────────────────┬──────────────────┬────────
  366.                                      │ A Procedure group│
  367.                                      │ B Procedure group│
  368.                                      │ C Procedure group│
  369.                                      └──────────────────┘
  370. It is best that you not use #!BREAK: at all unless the Norton Guide
  371. compiler reports the previously described error message.
  372.  
  373. #!BREAK: has no affect on PC-Browse databases and can be ignored.
  374.  
  375.  
  376. MACROS AND NG_MAKER___________________
  377.  
  378. In keeping with compatibility with the Make utility, NG_MAKER also
  379. includes macro expansion.  This lets you integrate a little
  380. flexibility into the Make control file.  Consider the following
  381. fragment from a Make control file.
  382.  
  383.  
  384. SRC=C:\ASSEMBLR\SS_SRCE\SRC=C:\ASSEMBLR\SS_SRCE\
  385.           .          .
  386.           .          .
  387.           .          .
  388. #!SOURCE:  $(SRC)SS.010#!SOURCE:  $(SRC)SS.010
  389. #!SOURCE:  $(SRC)SS.020#!SOURCE:  $(SRC)SS.020
  390. #!SOURCE:  $(SRC)SS.030#!SOURCE:  $(SRC)SS.030
  391.  
  392.  
  393. In this example, NG_MAKER will substitute every occurrence of "$(SRC)"
  394. with "C:\ASSEMBLR\SS_SRCE\" before working on the line.  One can use
  395. this feature to change how the program operates by simply changing one
  396. or two lines in the beginning of the control file.
  397.  
  398.  
  399.  
  400.  
  401.  
  402. Page 10                 Automatic Code Documentation        
  403. MODIFICATIONS TO THE PROJECT SOURCE CODE________________________________________
  404.  
  405. Now you have to make some changes to the actual source code. This step
  406. has been made as painless as possible.  As and example, consider the
  407. following assembly language procedure that prints out a string pointed
  408. to by DS:DX
  409.  
  410. ;============================================================;============================================================
  411. ;DICT Print;DICT Print
  412. ;;
  413. ; Enter with DS:DX pointing to a string ending in a $ symbol.; Enter with DS:DX pointing to a string ending in a $ symbol.
  414. ; Before printing, it places the cursor at row/col indicated by; Before printing, it places the cursor at row/col indicated by
  415. ; BH and BL; BH and BL
  416. ;-------------------------;-------------------------
  417. ;CALLS PlaceCursor ColorNormal;CALLS PlaceCursor ColorNormal
  418. ;ENDD;ENDD
  419. ;============================================================;============================================================
  420. PRINT           PROC    NEARPRINT           PROC    NEAR
  421.                 Call    ColorNormal                Call    ColorNormal
  422.                 Call    PlaceCursor                Call    PlaceCursor
  423.                 Mov     AH,09                Mov     AH,09
  424.                 Int     21h                Int     21h
  425.                 RET                RET
  426. PRINT           ENDPPRINT           ENDP
  427.  
  428.  
  429.  
  430. For the non-Assembler folks, the same thing in Pascal...
  431.  
  432. {============================================================}{============================================================}
  433. {DICT Print                                                  }{DICT Print                                                  }
  434. {{
  435. Syntax is PRINT(Row,Col, stuff_to_Print)Syntax is PRINT(Row,Col, stuff_to_Print)
  436. Places cursor and prints message on screen.Places cursor and prints message on screen.
  437. }}
  438. {-------------------                                         }{-------------------                                         }
  439. {CALLS PlaceCursor ColorNormal                               }{CALLS PlaceCursor ColorNormal                               }
  440. {ENDD                                                        }{ENDD                                                        }
  441. {============================================================}{============================================================}
  442. PROCEDURE  PRINT (Row,Col : INTEGER,Stuff : BigString);PROCEDURE  PRINT (Row,Col : INTEGER,Stuff : BigString);
  443. BEGINBEGIN
  444.     ColorNormal;    ColorNormal;
  445.     PlaceCursor(Row,Col);    PlaceCursor(Row,Col);
  446.     Write(Stuff);    Write(Stuff);
  447. END;END;
  448.  
  449.  
  450. Notice that in both examples, the actual code is preceded by a box
  451. that describes the purpose and expectations of the code block.  The
  452. general construction of this block is quite simple ...
  453.  
  454. <rem>  DICT  <procedure name> <endrem>       DICT                           
  455.  
  456. Page 11                 Automatic Code Documentation        
  457.       <Your explanation of the procedure. Can be as long as you want>
  458.  
  459. <rem>  CALLS <an optional list of other procedures that can be cross referenced>       CALLS                                                                    
  460. <rem>  ENDD  <endrem>       ENDD          
  461.  
  462.  
  463. As mentioned before, the keywords (DICT,CALLS,ENDD) are hidden behind
  464. whatever comment symbol is appropriate for that particular language.
  465. Notice one other thing: I used "====" and "----" bars inside the
  466. comment block to make things a bit easier to read.  NG_MAKER will take
  467. these out in the final database file.
  468.  
  469. That is all the changes that are required for your source code.  You
  470. may already have these header blocks in your code.  If so, simply add
  471. the DICT and ENDD lines (and CALLS line, if you wish) and you're all
  472. set!
  473.  
  474.  
  475.  
  476. PROGRAM MODULE DESCRIPTIONS___________________________
  477.  
  478. You may have found that you have grouped procedures of similar purpose
  479. together in the same file.  For instance, you may have placed all
  480. procedures that deal with printer I/O in a file called PROG1PRN.ASM.
  481. You can place a description of this module at the beginning of the file                                           at the beginning            
  482. to be extracted by NG_MAKER.  Its construction is as follows:
  483.  
  484. <rem>  DESC <endrem>       DESC         
  485.  
  486.       <Your explanation of the group of procedures.
  487.       <can be any number of lines long>
  488.  
  489. <rem>  ENDD  <endrem>       ENDD          
  490.  
  491.  
  492. To illustrate, examine the following fragment from the start of a file
  493. called MEGAPROJ.ASM
  494.  
  495.  
  496. ;DESC;DESC
  497. ;;
  498. ;The procedures in this file are responsible for the following:;The procedures in this file are responsible for the following:
  499. ;;
  500. ;1) Receive line input from the user.;1) Receive line input from the user.
  501. ;2) Handles DOS Critical Errors;2) Handles DOS Critical Errors
  502. ;3) Screen save and restore primatives.;3) Screen save and restore primatives.
  503. ;;
  504. ;;
  505. ; Note : A reminder to J.F. He has to make the screen saver routines; Note : A reminder to J.F. He has to make the screen saver routines
  506. ; faster. Too much snow on old CGA systems.; faster. Too much snow on old CGA systems.
  507. ;;
  508. ;ENDD;ENDD
  509.  
  510.  
  511. Page 12                 Automatic Code Documentation        
  512. See how the program director has used this feature to summarize the
  513. jobs that are handled by this file.  He also added some project
  514. management notes.
  515.  
  516. Sometimes a particular part of your program may involve a rather
  517. complex logic strategy.  I have found it very useful to describe this
  518. strategy in the DESC area of the file.  Later when I have to re-work
  519. the section of code,  I can review this explanation.
  520.  
  521. Norton Guide users will see these descriptions when they select the "BY
  522. FILE" option in the "SORTED" menu.  This will then display a listing of the
  523. files. Hilite a filename and press ENTER.  The DESCription will be shown
  524. under "FILE SUMMARY" followed by a list of procedures contained in
  525. that file.
  526.  
  527. PC-BROWSE users will find this information indexed under "FILE SUMMARY"
  528. which is at the bottom of the list of alphabetized procedures. Use
  529. Shift-PgDn to move down to it easier. Use the arrow keys to hilite "FILE
  530. SUMMARY" and press ENTER.
  531.  
  532.  
  533. RUNNING NG_MAKER________________
  534.  
  535. To start NG_MAKER on its way to extracting the comments from your
  536. source code, simply type NG_MAKER followed by the name of the Make
  537. control file.  If you wish to extract into a file compatible with PC-
  538. Browse, end the line with a   /BR.  Here are some examples :
  539.  
  540.  
  541. NG_MAKER  D:\ASSEMBLR\DT_SRCE\DTREENG_MAKER  D:\ASSEMBLR\DT_SRCE\DTREE
  542.  
  543. This uses the make file, DTREE and creates a series of files
  544. compatible with Norton Guides.
  545.  
  546. NG_MAKER  D:\ASSEMBLR\DL_OBJS\DLINK    /BRNG_MAKER  D:\ASSEMBLR\DL_OBJS\DLINK    /BR
  547.  
  548. This uses the make file, DLINK and creates a file compatible with PC-
  549. Browse.
  550.  
  551.  
  552.  
  553. A NOTE FOR PC-BROWSE USERS__________________________
  554.  
  555. You lesson stops here!  The final file is completely PC-Browse
  556. compatible and can be used immediately.
  557.  
  558.  
  559. COMPILING NORTON GUIDE______________________
  560.  
  561. Norton Guide users must complete one final step which is the
  562. compilation and linking of the files created with NG_MAKER.
  563. Fortunately, a simple batch file called QNG.BAT does it all.  You will
  564. Page 13                 Automatic Code Documentation        
  565. find this file included on your NG_MAKER disk.  Copy it to the
  566. subdirectory containing the NGC.EXE and NGML.EXE programs from your
  567. Norton Guide disk.
  568.  
  569. To run the batch file, simply enter QNG followed by the name of the
  570. file specified in the #!OUT: line of the make file you just used. For
  571. example, if you Make file contained the line:
  572.  
  573. #!OUT: C:\NORGUIDE\PROJX#!OUT: C:\NORGUIDE\PROJX
  574.  
  575. Run the batch file as      QNG  C:\NORGUIDE\PROJX                           QNG  C:\NORGUIDE\PROJX
  576.  
  577. or simply       QNG  PROJX      if you told the Make file to create                QNG  PROJX                                         
  578. PROJX in the same directory that holds QNG.BAT, NGC.EXE and NGML.EXE.
  579.  
  580.  
  581. Page 14                 Automatic Code Documentation        
  582.  
  583. ABOUT THE AUTHOR________________
  584.  
  585. Steven Kurtz is the author of the hard disk manager, Direc-Tree and
  586. Direc-Link, a file transfer utility program. Both programs are
  587. published by the Micro-Z Company.  A new program, Del/Elite is still
  588. looking for a publisher at this time.
  589.  
  590.  
  591. COPYRIGHT NOTICE AND LICENSE____________________________
  592.  
  593. Steven W. Kurtz, the copyright owner for NG_MAKER, hereby licenses you
  594. to: use the software; make as many copies of the shareware version of
  595. this software and documentation as you wish; give exact copies of the
  596. original shareware version to anyone; and distribute the shareware
  597. version of the software and documentation in its unmodified form via
  598. electronic means. There is no charge for any of the above.
  599.  
  600. This is not free software.  This license allows you to use this software
  601. without charge for a period of 30 days. In order to include this
  602. software as part of any product, either commercial, shareware,
  603. freeware, or public domain, registration is required. Any such use of
  604. NG_MAKER is in violation of federal copyright laws and will be
  605. prosecuted.
  606.  
  607. No copy of the software may be distributed or given away without this
  608. accompanying documentation; this notice must not be removed.  ONLY
  609. COPIES OF THE SHAREWARE VERSION MAY BE DISTRIBUTED IN ANY FORM.
  610.  
  611. WARRANTY________
  612.  
  613. There is no warranty of any kind associated with this software, and
  614. the copyright owner is not liable for damages of any kind.  By using
  615. this software, you agree to this. Every effort has been made by me to
  616. make this product bug-free.  However, the nature of software
  617. development is that it is impossible to guarantee bug-free software. If a
  618. registered user reports a verifiable bug, the user will receive a free
  619. upgrade to the next version of NG_MAKER.
  620.  
  621. REGISTRATION____________
  622.  
  623. Upon receipt of the appropriate registration fee, I will send the user a
  624. printed copy of this documentation, and a disk containing the latest
  625. version of NG_MAKER.
  626.  
  627. Page 15                 Automatic Code Documentation        
  628.  
  629. TECHNICAL SUPPORT_________________
  630.  
  631. Questions regarding NG_MAKER are given to registered users via
  632. Compuserve or Prodigy Electronic mail
  633.  
  634.  
  635. Steven W. Kurtz
  636. 1433 Summerland Ave.
  637. San Pedro, CA 90732
  638. Compuserve 73577,2271
  639. Prodigy    MDKS67A
  640.  
  641.  
  642.  
  643.  
  644.  
  645. VERSION HISTORY_______________
  646.  
  647.  
  648. 1.0             First release
  649. 2.0             Add sorting
  650.                 Support for PC-Browse
  651. 2.1 - 2.4       Internal use by me
  652. 2.5             Released to public
  653. 2.6             Fix problem with ENDMARKs
  654. 2.7             Added DESC feature
  655.                 Sort gets it own menu in Norton Guides
  656.  
  657.  
  658.  
  659.